package com.kexio.auth.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 权限验证注解
 * 
 * 标注在控制器方法或类上，用于验证当前用户是否具有指定权限。
 * 支持单个权限和多个权限验证，以及AND/OR逻辑关系。
 * 
 * <pre>
 * &#64;GetMapping("/users")
 * &#64;RequiresPermission("system:user:list")
 * public Result&lt;List&lt;UserDTO&gt;&gt; getUsers() {
 *     return userService.getUserList();
 * }
 * 
 * &#64;PostMapping("/users")
 * &#64;RequiresPermission(value = {"system:user:create", "system:user:manage"}, logical = Logical.OR)
 * public Result&lt;Void&gt; createUser(&#64;RequestBody CreateUserRequest request) {
 *     userService.createUser(request);
 *     return Result.success();
 * }
 * </pre>
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequiresPermission {
    
    /**
     * 权限逻辑枚举
     */
    enum Logical {
        /**
         * AND - 需要同时拥有所有权限
         */
        AND,
        
        /**
         * OR - 只需拥有其中任意一个权限
         */
        OR
    }
    
    /**
     * 所需权限码
     * 
     * 单个权限：@RequiresPermission("system:user:list")
     * 多个权限：@RequiresPermission({"system:user:list", "system:user:create"})
     * 
     * @return 权限码数组
     */
    String[] value();
    
    /**
     * 多个权限之间的逻辑关系
     * 
     * @return 逻辑关系，默认为AND（需要同时拥有所有权限）
     */
    Logical logical() default Logical.AND;
    
    /**
     * 权限验证失败时的错误消息
     * 
     * @return 错误消息，为空时使用默认消息
     */
    String message() default "";
    
    /**
     * 是否忽略超级管理员权限检查
     * 
     * @return true-超级管理员跳过权限验证，false-所有用户都需验证权限
     */
    boolean ignoreSuperAdmin() default true;
    
    /**
     * 权限验证级别
     * 
     * STRICT - 严格验证，必须完全匹配权限码
     * LOOSE - 宽松验证，支持通配符匹配（如 system:user:* 匹配 system:user:list）
     * 
     * @return 验证级别，默认为严格验证
     */
    VerifyLevel level() default VerifyLevel.STRICT;
    
    /**
     * 是否自动聚合数据权限上下文
     * 
     * 当设置为true时，如果当前上下文中没有DataScope设置，
     * 将自动根据用户信息创建数据权限上下文：
     * - 有部门的用户：设置为DEPT权限
     * - 无部门的用户：设置为SELF权限
     * 
     * @return true-自动聚合数据权限，false-不处理数据权限
     */
    boolean aggregateDataScope() default false;
    
    /**
     * 权限验证级别枚举
     */
    enum VerifyLevel {
        /**
         * 严格验证 - 精确匹配权限码
         */
        STRICT,
        
        /**
         * 宽松验证 - 支持通配符匹配
         */
        LOOSE
    }
}
